table of contents
TRACELOG(3) | LTTng Manual | TRACELOG(3) |
NAME¶
tracelog - LTTng-UST printf(3)-like interface with a log level
SYNOPSIS¶
#include <lttng/tracelog.h>
#define tracelog(level, fmt, ...)
Link with -llttng-ust.
DESCRIPTION¶
The LTTng-UST tracelog() API allows you to trace your application with the help of a simple printf(3)-like macro, with an additional parameter for the desired log level. The fmt argument is passed directly to the fmt parameter of vasprintf(3), as well as the optional parameters following fmt.
The purpose of tracelog() is to ease the migration from logging to tracing.
The available values for the level parameter are:
TRACE_EMERG
TRACE_ALERT
TRACE_CRIT
TRACE_ERR
TRACE_WARNING
TRACE_NOTICE
TRACE_INFO
TRACE_DEBUG_SYSTEM
TRACE_DEBUG_PROGRAM
TRACE_DEBUG_PROCESS
TRACE_DEBUG_MODULE
TRACE_DEBUG_UNIT
TRACE_DEBUG_FUNCTION
TRACE_DEBUG_LINE
TRACE_DEBUG
To use tracelog(), include <lttng/tracelog.h> where you need it, and link your application with liblttng-ust. See the EXAMPLE section below for a complete usage example.
Once your application is instrumented with tracelog() calls and ready to run, use lttng-enable-event(1) to enable the lttng_ust_tracelog:* event. You can isolate specific log levels with the --loglevel and --loglevel-only options of this command.
The tracelog() events contain the following fields:
Field name | Description |
line | Line in source file where tracelog() was called |
file | Source file from which tracelog() was called |
func | Function name from which tracelog() was called |
msg | Formatted string output |
If you do not need to attach a specific log level to a tracelog() call, use tracef(3) instead.
See also the LIMITATIONS section below for important limitations to consider when using tracelog().
EXAMPLE¶
Here’s a usage example of tracelog():
#include <stdlib.h> #include <lttng/tracelog.h> int main(int argc, char *argv[]) {
int i;
if (argc < 2) {
tracelog(TRACE_CRIT, "Not enough arguments: %d", argc);
return EXIT_FAILURE;
}
tracelog(TRACE_INFO, "Starting app with %d arguments", argc);
for (i = 0; i < argc; i++) {
tracelog(TRACE_DEBUG, "Argument %d: %s", i, argv[i]);
}
tracelog(TRACE_INFO, "Exiting app");
return EXIT_SUCCESS; }
This C source file, saved as app.c, can be compiled into a program like this:
cc -o app app.c -llttng-ust
You can create an LTTng tracing session, enable all the tracelog() events, and start the created tracing session like this:
lttng create my-session lttng enable-event --userspace 'lttng_ust_tracelog:*' lttng start
Or you can enable tracelog() events matching a log level at least as severe as a given log level:
lttng enable-event --userspace 'lttng_ust_tracelog:*' \
--loglevel=TRACE_INFO
Next, start the program to be traced:
./app a few arguments passed to this application
Finally, stop the tracing session, and inspect the recorded events:
lttng stop lttng view
LIMITATIONS¶
The tracelog() utility macro was developed to make user space tracing super simple, albeit with notable disadvantages compared to custom, full-fledged tracepoint providers:
Thus, tracelog() is useful for quick prototyping and debugging, but should not be considered for any permanent/serious application instrumentation.
See lttng-ust(3) to learn more about custom tracepoint providers.
BUGS¶
If you encounter any issue or usability problem, please report it on the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-ust>.
RESOURCES¶
COPYRIGHTS¶
This macro is part of the LTTng-UST project.
This macro is distributed under the GNU Lesser General Public License, version 2.1 <http://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html>. See the COPYING <https://github.com/lttng/lttng-ust/blob/master/COPYING> file for more details.
THANKS¶
Thanks to Ericsson for funding this work, providing real-life use cases, and testing.
Special thanks to Michel Dagenais and the DORSAL laboratory <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for the LTTng journey.
AUTHORS¶
LTTng-UST was originally written by Mathieu Desnoyers, with additional contributions from various other people. It is currently maintained by Mathieu Desnoyers <mailto:mathieu.desnoyers@efficios.com>.
SEE ALSO¶
tracef(3), lttng-ust(3), lttng(1), printf(3)
06/05/2016 | LTTng 2.9.0-pre |